home *** CD-ROM | disk | FTP | other *** search
/ Power Programmierung / Power-Programmierung (Tewi)(1994).iso / assemblr / library / sampler0 / ovlmgr.doc < prev    next >
Text File  |  1989-11-27  |  10KB  |  201 lines
  1.              Brief notes about ovlmgr.asm
  2.              ----------------------------
  3.              (revised 1989nov12)
  4.  
  5. OVLMGR.ASM is a preliminary version of a multiple-residency overlay
  6. manager for use with the Microsoft Overlay Linker. It is functionally
  7. compatible with the one in the MSC library _except_:
  8.  
  9. - it doesn't support setjmp()/longjmp().
  10. - it leaves only a SMALL, fixed space for your heap (1).
  11. - it usually accesses the disk less often and is a lot faster in some
  12.   applications.
  13. - it has different tuning characteristics.
  14. - you must (of course) link OVLMGR.OBJ into the root overlay (that is,
  15.   outside any parentheses in the link command).
  16.  
  17.   See also the bugs list below.
  18.  
  19. As with other Microsoft-compatible overlay handlers you must be *very*
  20. careful never to call a function in an overlay through a pointer,
  21. unless the initiator of the call resides in the *same* physical
  22. overlay as the target (2).
  23.  
  24. Although using the overlay manager is in essence much like using
  25. Microsoft's, they operate on a slightly different principle, and tuning
  26. for them is rather different. Technical part begins.
  27.  
  28. When overlay linking is requested (see you linker manual), the MS
  29. overlay linker changes all far calls into overlays from the (normal,
  30. 8086) format:
  31.  
  32.     offset    contents
  33.     ------    --------
  34.     :0000    CALL
  35.     :0001    target-offset
  36.     :0003    target-segment
  37.  
  38. to this:
  39.     :0000    INT
  40.     :0001    int#    target-mod#
  41.     :0003    target-offset
  42.  
  43. (note that here we are looking at the actual layout of the machine
  44. code, not at the assembly code as such) and relocates the code parts
  45. of all the different overlays into the *same* physical area. The
  46. overlaid code is all actually placed at the end of the .EXE file,
  47. after the 'normal' executable image, along with all its administrative
  48. data (fixups etc.).
  49.     When this altered 'call' is executed, of course, the interrupt
  50. handler int# is invoked. Its job is to ensure that the target overlay
  51. module is in memory (reading it from the tail of the .EXE file if it
  52. isn't already loaded) and then transfer to the given offset within it,
  53. 'faking up' the effect of the 'real' far call that would normally have
  54. occurred.  Something similar must be done when the call returns, to
  55. ensure that the thing being returned *into* is still (or is once more)
  56. loaded.
  57.     The Microsoft linker, as we have said, relocates all the
  58. overlays to the same load address; and, in fact, it allocates am empty
  59. block of memory there that is at least as large as the largest
  60. overlay. Into this area all the overlays are loaded without further
  61. change; thus, there can only ever be one overlay in memory at one
  62. time. Transferring from one overlay to another causes one overlay to
  63. replace the other in the allocated overlay swap area.
  64.     Our overlay manager does not use the space allocated by the
  65. linker in the same way. Rather, it allocates almost all of the memory
  66. available from MS-DOS (including the original overlay area). As
  67. overlays are needed, they are loaded wherever they will fit, and
  68. dynamically relocated to that address.    Thus, many more than one
  69. overlay may be loaded at any given time, greatly increasing potential
  70. performance. Managament of space is more or less according to an LRU
  71. policy - once all of memory is full, the least recently used overlay
  72. is selected as the most likely candidate for replacement.
  73.  
  74. The implications of this difference are as follows: while with the
  75. conventional (default) overlay manager, the best strategy is to group
  76. object modules together in an overlay whenever they are known to be
  77. used in rapid succession, to make each overlay as big as possible (all
  78. things being equal) in order to take advantage of all available
  79. memory, and to make as few overlays as possible (to reduce the amount
  80. of disk access), the best strategy with our overaly manager is almost
  81. the reverse. Having a lot of small overlays will increase the amount
  82. of useful stuff that can be resident in memory at the same time; all
  83. of memory will automatically be employed; and there is no advantage at
  84. all to uniformity of size (except perhaps in the unlikely case of
  85. *exact* uniformity!).
  86.     One thing that is no longer a problem with this version
  87. (though it was with all earlier versions of this overlay manager) is
  88. that the DOS exec() call works normally. The memory that is allocated
  89. for administering the overlay system is freed before the exec call is
  90. made and reallocated afterwards (we trap the DOS function request
  91. vector to do this, which isn't very nice as a programming practise but
  92. makes the existence of the overlay manager far more transparent).
  93. There is, however, one circumstance under which this can be
  94. problematic: if you use the exec() call to load a TSR application,
  95. thereby causing memory that the overlay manager was using to become
  96. unavailable, you may make it impossible for the overlaid application
  97. to proceed. This is because code that is nominally 'running' (i.e. is
  98. currently on the stack) cannot be relocated and must be reloaded
  99. at the *same address* that previously held it. If another process now
  100. owns that area of memory, there is nothing we can do.
  101.     We believe that this should not be a serious concern in normal
  102. use.
  103.  
  104. NOTA BENE: This is a preliminary version of the overlay manager, but
  105. by now it should be fairly well debugged. If you are considering
  106. upgrading it please be aware that the following improvements are
  107. planned for the next version (though who knows when delivery will
  108. occur):
  109.     Twice the speed
  110.     EMS support
  111.     compatible versions of setjmp() and longjmp()
  112.     Integration with malloc() so the heap can grow
  113.     Major code revamping
  114.  
  115. Enjoy!
  116. ------------------------------------------------------------------------
  117. MESSAGES
  118.  
  119. Not enough memory to run this program. Time to go to the store.
  120.     Although DOS successfully loaded the programme, it proved
  121.     impossible to allocate enough additional contiguous memory to
  122.     load one or more of the overlays. Either reduce the
  123.     RAM-loading of the application by reducing the size of either
  124.     the root or the largest overlays, or increase the amount of
  125.     memory available by unloading TSRs and/or simplifying your
  126.     CONFIG.SYS.
  127.  
  128. Your dog eats all your remaining memory! You die.
  129.     Either an internal error has occurred in ovlmgr or the
  130.     application programme, or some event has caused memory that
  131.     ovlmgr believed it could count on becoming unavailable. A
  132.     typical example of the latter would be the result of
  133.     attempting to load a TSR while an overlaid application is
  134.     running.
  135.  
  136. The Nymph stole your .EXE file! You die.
  137.     For some reason ovlmgr could not locate or read the original
  138.     .EXE file in which the overlays reside. This could be due to
  139.     your attempting to use a very old version of DOS,
  140.     an abject shortage of file handles, some strange event causng
  141.     the file to be deleted, a disk error, or the diskette that
  142.     contained the executable has been removed.
  143. ------------------------------------------------------------------------
  144. KNOWN BUGS
  145.  
  146. The present version cannot always be used as a direct replacement for
  147. Microsoft's overlay manager (even granted the documented differences)
  148. because the minimum size required for an overlaid programme to run is
  149. at least the size of the root plus TWICE the size of the largest
  150. overlay. If a programme has previously had its overlay structure tuned
  151. to take best advantage of Microsoft overlays, this may well cause a
  152. problem. The overlays themselves will need to be split up.
  153.  
  154. The error messages are whimsical and NetHack-culture-specific.
  155. Somewhat more informative versions appeared in one version of the
  156. programme but they seem to have been lost.
  157.  
  158. Transfers between overlays are very slow in machine terms, even if
  159. both overlays happen to reside in memory at the time.
  160.  
  161. Locking overlays into memory is not really implemeted even though
  162. reading the source code might make you think it was.
  163. ------------------------------------------------------------------------
  164. BUG ALERT
  165.  
  166. To repeat a point made above, if you ever try to call a function in an
  167. overlay through a pointer, you *may* die with the Microsoft overlay
  168. manager. If you ever try to call a function in an overlay through a
  169. pointer, you *will* die with ours. Nothing in an overlay ever ends up
  170. in the same segment as the linker anticipated.    You have been warned!
  171. ------------------------------------------------------------------------
  172. FOOTNOTES
  173.  
  174. (1) If you hunt through the code you will find a magic constant you
  175. can play with to vary this allotment, if you're brave enough. It's
  176. currently tuned for NetHack 3.0. If you should get a message to the
  177. effect that NetHack can't allocate 28000 and some bytes when entering
  178. a maze level, that isn't our problem! In all probability you forgot to
  179. rebuild your special level files when you changed the compiler flags.
  180. We got that one, too, at one point.
  181.  
  182. (2) This problem can be circumvented through the use of surrogate
  183. 'trampoline' functions: functions that reside in the root overlay and
  184. simply pass right through to the 'real', overlaid, implementations.
  185. This can even be made transparent to the source code through the use
  186. of the C macro preprocessor, with a locution of the form
  187.     #define foo(x) foo_(x)
  188. visible everywhere except at the actual definition point of the
  189. trampoline. This has been implemented in Nethack 3.0h.
  190. ----------------------------------------------------------------------
  191. NOTICE
  192.  
  193. OVLMGR.ASM is brought to you by Pierre Martineau and Stephen Spackman.
  194. It, and this document, are copyright. They are, however, provided as
  195. part of NetHack and may be freely distributed as described in the
  196. NetHack license.
  197. ----------------------------------------------------------------------
  198. Stephen P Spackman               stephen@concour.cs.concordia.ca
  199. ----------------------------------------------------------------------
  200.      Copyright (C) 1989 Pierre G Martineau and Stephen P Spackman
  201.